命名空間

在 TypeSpec 中可使用命名空間 namespace 來分類類型，透過這樣的方式可以組織不同類型，也可以避免命名衝突，範例程式碼如下：

namespace MemberService;
// 以下開始撰寫的程式碼屬於 MemberService 這個 namespace

命名空間中可以有其他命名空間，使用 {} 或 . 來表達階層關係，例如 MemberService 中的 Member 命名空間程式碼如下：

namespace MemberService.Member;
// 以下開始撰寫的程式碼屬於 MemberService.Member

或

namespace MemberService {
    namespace Member {
        // 這邊撰寫的程式碼屬於 MemberService.Member
    }
}

我個人習慣一個檔案內只有一個命名空間，並讓命名空間結構和檔案目錄結構對齊，這樣比較好管理。當需要使用命名空間中的類型時，可使用 using 關鍵字，若要使用的命名空間定義在其他檔案時，需使用 import 才能正確參照，範例程式碼如下：

// member/member.tsp
namespace MemberService.Member;

// main.tsp
import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";
import "./member/member.tsp";

using TypeSpec.Http;
using MemberService.Member;

@service({
    title: "會員服務",
    version: "1.0.0"
})
@server("https://api.example.com/v1", "正式環境")
@server("https://api.staging.example.com/v1", "測試環境")
namespace MemberService;

操作 (API)

每一支 API 就是一個行為，像是：取得會員、註冊會員......等，在 TypeSpec 中可透過操作 (Operation) 在命名空間中定義這些操作的介面。

1. 宣告操作

使用關鍵字 op 宣告一個操作，接著宣告它的名字、參數和回傳，例如宣告 MemberService 有一支 HealthCheck API(healthCheck)，沒有傳入參數(() 內為空)，回傳為空({} 內為空)，範例程式碼如下：

import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";

using TypeSpec.Http;

@service({
    title: "會員服務",
    version: "1.0.0"
})
@server("https://api.example.com/v1", "正式環境")
@server("https://api.staging.example.com/v1", "測試環境")
namespace MemberService;

op healthCheck(): {};

2. 宣告 HTTP 方法及路由

TypeSpec.Http 提供了 HTTP 請求所需的裝飾器，包含常見的 @get、@post、@put、@patch、@delete...... 等等，以及設定路由的 @route 裝飾器。

使用 @get 裝飾器指定操作的 HTTP 方法為 GET，並使用 @route 裝飾器指定操作的路由為 _hc，範例程式碼如下：

// 以上省略

namespace MemberService;

@get()
@route("_hc")
op healthCheck(): {};

3. 撰寫 API 說明

使用 @summary 裝飾器宣告 API 名稱，並用 @doc 裝飾器撰寫 API 詳細說明。在 TypeSpec 中使用三個雙引號可撰寫多行文字，範例程式碼如下：

// 以上省略

namespace MemberService;

@get()
@route("_hc")
@summary("確認服務健康狀態")
@doc("""
    這個 API 用來確認服務是否正常運作。
    這個 API 不需要任何參數，只要回應 200 即表示服務正常。
""")
op healthCheck(): {};

這時編譯後會看到 openapi.yaml 在 paths 節點下產生了對應的內容如下：

openapi: 3.0.0
info:
  title: 會員服務
  version: 1.0.0
tags: []
paths:
  /_hc:
    get:
      operationId: healthCheck
      summary: 確認服務健康狀態
      description: |2-
            這個 API 用來確認服務是否正常運作。
            這個 API 不需要任何參數，只要回應 200 即表示服務正常。
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
components: {}
servers:
  - url: https://api.staging.example.com/v1
    description: 測試環境
    variables: {}
  - url: https://api.example.com/v1
    description: 正式環境
    variables: {}

Redoc 預覽如下：

明天將介紹 TypeSpec 的基礎型別。